XGS: The Portable Apple IIGS(tm) emulator
Version 0.46 -- January 11th, 1997
Written and (C) 1996-97 by Joshua M. Thompson

-----------
LEGAL STUFF
-----------

You may distribute this program so long as you do not sell it (selling a CD
of freeware and shareware does not qualify as selling it). All I ask is that
you keep this file intact, and that you include the source code.

Many thanks to Kent Dickey (kentd@hpcuhe.cup.hp.com). Kent not only gave me
a hell of a lot of nice ideas (like the memory handling subsystem for the
slow memory banks), but he even donated code to the project. Thanks, Kent!

I'd also like to thank anyone who has done work on porting XGS to non-Unix
platforms. Their names and email addresses are listed in the PORTS file in
the docs/ subdirectory.

Apple, IIGS, Apple IIGS, and GS/OS are registered trademarks of Apple
Computer, Inc.  All rights reserved.

------------
CONTACT INFO
------------

I can be reached via Internet email as invid@optera.com, and sometimes on
IRC (EFnet) as LrdRayden.

The latest versions of this code will be made available through the XGS
home page. The URL is "http://www.optera.com/~invid/emulators/XGS/".

There is also a mailing list for discussing XGS issues. You can subscribe
by sending mail to "majordomo@optera.com" and including the words
"subscribe xgs-list" on a line by itself in the body of the letter. I
strongly suggest you subscribe to it if you're going to use XGS.

------------
INTRODUCTION
------------

XGS is a program to emulate an Apple IIGS on a Unix system under X Windows.
This is an alpha version; many features are not implemented yet, and many
others don't work exactly like they should.

The following features are currently implemented:

o CPU emulation
o Memory map emulation
o All known video modes
o Ensoniq sound
o ADB keyboard
o ADB mouse
o Joystick (follows mouse movement)
o Clock chip
o Battery RAM
o IWM hardware emulation for drives in slots 5 and 6 (3.5" / 5.25")
o A 14-unit Extended SmartPort device in slot 7

The following features are NOT currently implemented:

o 3.5" drive emulation is currently broken; the code is mostly there but I am
  still lacking a few crucial bits of information.
o 5.25" drive emulation is currently read-only. There is skeleton code in place
  to handle writes but it currently doesn't do anything.
o Serial ports
o Many, many other minor things.

-------------------
SYSTEM REQUIREMENTS
-------------------

o A 90 MHz Pentium or better (it will run on slower, but it'll be virtually
  unusable.)

o A compatible operating system. Ports are currently available for Unix
  systems running an 8-bit X server and for Win32 with DirectX.

o A copy of the ROMs from a ROM 01 or 03 Apple IIGS (see "How to Use It" below).

--------------------------
HOW TO COMPILE (UNIX ONLY)
--------------------------

Please read this entire section through at least once before you do anything.

XGS uses the GNU autoconf packages to make configuration quick and painless.
Simply type "./configure" and XGS will (on most systems) configure itself. You
may want to glance over the Makefile and config.h file after doing this, just
to make sure they are correct.

Once XGS is configured, type "make depend" to generate the Makefile
dependancies. You can then type "make install" to build and install XGS. The
default install location is under /usr/local (/usr/local/bin/xgs for the binary
and /usr/local/lib/xgs for the fonts and other support files). You can change
this with the --prefix option to configure.

The default configuration generated by the configure program will build a
version of XGS that emulates a ROM 01 without sound or MIT shared memory
support. Other configurations are possible by passing additional parameters
to the configure command:

--with-x		Enable X11 support. If you _don't_ select this, then
			an svgalib version of XGS will be built instead.

--with-oss-sound	Enable sound support for systems supporting the Open
			Sound System API (the "/dev/dsp" device; Linux and
			FreeBSD are in this category).

--with-mit-shm		Enable support for the MIT shared memory extensions
			to X. XGS will then use shared memory to talk to the
			X server whenever it can.

--with-debug		Enable debugging support, such as the trace mode in
			the CPU emulator. You can leave this disabled unless
			you're trying to track down a problem in XGS.

There are also some useful support utilities included with XGS. To build and
install them, type "make install-utils". They will be installed in the same
directory as the XGS binary.

-------------
HOW TO USE IT
-------------

You will need a ROM image file to make XGS run. You can get the ROMs from a
IIGS by saving them out in 32 KB chunks in AppleSoft BASIC. Boot a ProDOS 8
disk and get into BASIC, then do the following:

**** For a ROM 01 machine: ****

] CALL -151
* 00/800<FE/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000
* 00/800<FE/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$8000
* 00/800<FF/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$10000
* 00/800<FF/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$18000

**** For a ROM 03 machine: ****

] CALL -151
* 00/800<FC/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000
* 00/800<FC/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$8000
* 00/800<FD/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$10000
* 00/800<FD/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$18000
* 00/800<FE/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$20000
* 00/800<FE/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$28000
* 00/800<FF/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$30000
* 00/800<FF/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$38000

The resulting XGS.ROM file should be exactly 131,072 bytes long for a ROM 01
image or 262,144 bytes long for a ROM 03 image. If it isn't then you messed up
somewhere...go back and try again.

You now have to get the file over to your machine. If you've got a Mac this is
easy; the Macintosh can read the IIGS floppy directly. Otherwise you're going
to have to use a serial cable or modem to transfer the file from the IIGS to
your machine.

If you don't have a real IIGS to get the ROMs from then you're on your own.
Apple owns the copyrights on the ROMs, so I can't legally give you a copy (nor
can anyone else). As a result you're probably not going to find them on an FTP
site anywhere.

I will repeat this one more time:

*** I CANNOT (AND WILL NOT) GIVE YOU A COPY OF THE IIGS ROM!! ***
*** SO DON'T SEND ME MAIL AND AND ME ABOUT IT. IT WON'T HELP. ***

Now that that's out of the way, let's move on to actually running the program.
The following support files must be in the XGS lib directory (normally this
will be /usr/local/share/xgs on Unix or C:\XGS on Windows):

xgs40.fnt	The Apple II 40-column screen font
xgs80.fnt	The Apple II 80-column screen font
xgs.rom		The ROM image 
xgs.ram		The battery ram save file

If everything looks OK then start XGS. For Unix systems, just type "xgs" and
hit RETURN; for Windows systems double-click on the XGS program icon.

If everything goes well, you should see the virtual IIGS boot and dump you
into AppleSoft BASIC (because you don't have any boot disk image yet -- more
on that later). If you don't get the BASIC screen then you have a problem;
refer to the "Troubleshooting" section below.

While XGS is running, there are several special key sequences you can use
to control the emulator:

Control-End		Does just that -- ends (quits) XGS.

Control-Home		Sends a Control-Reset to the emulator.

Control-PageUp		Turns on trace mode (if you conmpiled
			with -DDEBUG). Note that on Windows
			the trace output goes into the
			BOOTLOG.TXT file.

Control-PageDown	Turns off trace mode (if you compiled
			with -DDEBUG).

Pause			Sends a Non-Maskable Interrupt (NMI) to
			the emulator. This is a guaranteed way
			to get into the monitor and poke around.
			This also dumps a copy of banks $00 and $01
			into banks $E8 and $E9 for debugging
			purposes.

F1			(Win32 only). This is the IIGS escape key.
			The real escape key causes problems with
			Windows because certain key sequences are
			reserved by Windows (Alt-Escape, for example).

F5			Toggle joystick emulation on/off. Note that
			you can't turn on joystick emulation unless
			mouse emulation is off!

F6			Toggle mouse emulation on/off. Note that you
			can't turn on mouse emulation unless joystick
			emulation is off!

Most other keypresses are just passed on to the emulated IIGS to be interprted
by whatever program is currently running.

Whenever joystick or mouse emulation is on, the pointer is confined to the XGS
window. Turn off the joystick or mouse emulation to move the pointer to other
windows.

The default for the emulator is to emulate a 2 MB machine. To change this, add
the "-ram #" option to the xgs command line, where # is the number of megabytes
to emulate (must be between 1 and 8).

To disable sound emulation (which signifigantly speeds up XGS), start XGS with
the "-nosound" command line option.

-----------------
USING DISK IMAGES
-----------------

XGS allows you to mount files as Apple IIGS disks. These files (called disk
images) must be in a specific format for XGS to recognize them.

To mount images on the virtual GS, use the following command line options when
you first start XGS (you can't currently switch images while XGS is running;
this is planned as a future enhancement however):

-s5d1 <image>		Mounts an image on Slot 5, Drive 1 (the first 3.5"
			disk drive). The image must be exactly 1,600 ProDOS
			blocks in size or it will not be loaded.

-s5d2 <image>		Same as above, but mounts the image on Slot 5, Drive 2.

-s6d1 <image>		Mounts an image on Slot 6, Drive 1 (the first 5.25"
			disk drive). The imge must be exactly 280 ProDOS blocks
			in size or it will not be loaded.

-s6d2 <image>		Same as above, but mounts the image on Slot 6, Drive 2.

-smptX <image>		Mounts an image as device number X (where X is between
			0 and 13) on the SmartPort in slot 7. Device #0 is the
			boot device and is mapped to Slot 7, Drive 1. The
			remaining devices are mapped to additional slot/drive
			combinations under ProDOS 8 v2.0 and higher (under GS/OS
			they will be directly accessible).

XGS comes with several utilities to make dealing with images easier. They are:

    dc2img <source file> <destination file>

	This program converts a Macintosh DiskCopy image file into an XGS
	image. If you have a Macintosh, you can use DiskCopy to create images
	of your IIGS disks, and then transfer those images to your Unix system
	and run them through this program to create XGS images.

	Apple usually distributes system software (such as GS/OS) as DiskCopy
	images as well.

    raw2img <source file> <destination file>

	This program converts a "raw" disk dump into an XGS image. The raw data
	must be in ProDOS block order, such as the ".PO" disk images used by
	some other Apple II emulators. Unshrinking a disk image with nulib on
	Unix also produces a file in this format.

    dsk2img <source file> <destination file>

	Converts a DOS 3.3 sector-ordered image into an XGS image. These images
	are the most common image format on other emulators, and usually have
	filenames ending in ".DO" or ".DSK"

    newimg <output file> <size in KB>

	Creates a new, blank image file of the specified size. The size can be
	anywhere between 16 and 32767 KB (32 MB).

    imginfo <image file>

 	Displays statistics on an image file, such as its name, size in blocks,
	write protect status, and comments.

    lockimg <image file>

	Write protects ("locks") an image file. When an image is locked, XGS
	will refuse to write to it; any write attempts will result in a
	"WRITE PROTECTED" error.

    unlockimg <image file>

	Write enables ("unlocks") an image file. Once an image is unlocked,
	it can be written to by XGS (including formatted).

---------------
TROUBLESHOOTING
---------------

If the XGS screen doesn't appear, then the emulator probably couldn't start,
and you should read the startup output to figure out why.  You probably have a
missing file. On Windows systems, the startup output is saved into the file
BOOTLOG.TXT in the same directory as XGS.EXE.

If the screen appears and then disappears, then the emulator probably crashed.
Mail me a bug report. If you're really ambitious you can even try to debug it
yourself.

If XGS crashes while running a certain piece of software, see if you can
reproduce the crash and tell me how you did it.  Even better, try to send
me a snippit of XGS debug output that shows the instruction that caused the
crash, along with a hundred or so lines preceding the crash.
